| blob | f68287c42375a34fc698833f4f9f33043dbdccd4 |
2 <html>
3 <head>
6 <title></title>
31 </style>
32 </head>
33 <body>
36 <p class="p3">The easiest way to get sound from SC is to use a Function. Below is a simple example of this. Execute this (after making sure the server is booted), and when you're sick of it, press Cmd - . (that's hold down the command key and press the period or fullstop key) to stop the sound. This will always stop all sound in SC. You'll be using it a lot, so commit it to memory.</p>
38 <p class="p4"><span class="s1"><span class="Apple-tab-span"> </span></span>{ [<span class="s2">SinOsc</span>.ar(440, 0, 0.2), <span class="s2">SinOsc</span>.ar(442, 0, 0.2)] }.play;</p>
40 <p class="p3">Not too inspiring? Don't worry, we're just getting started, and this is just a simple example to demonstrate Functions and sound. We'll take it apart a bit below.<span class="Apple-converted-space"> </span></p>
42 <p class="p3">Before we get to doing that though, let's learn a little about Functions in general.<span class="Apple-converted-space"> </span></p>
44 <p class="p3">A Function is just a reusable bit of code. You define a Function by enclosing code in 'curly brackets': { }. Here's an example:</p>
46 <p class="p5"><span class="s3"><span class="Apple-tab-span"> </span></span><span class="s4">f = { </span>"Function evaluated"<span class="s4">.postln; };</span></p>
48 <p class="p3">The stuff within the curly brackets is what will get executed each time you reuse, or evaluate the Function. Note that this is written like an equation, i.e. <span class="s5">f = {...}</span>. This is not an equation in the mathematical sense, it's what's called an assignment. Basically it allows me to name the Function I've created, by storing it in a variable called '<span class="s5">f</span>'. A variable is just a name representing a slot in which we can store things, such as a Function, a number, a list, etc. Execute the following lines one at a time and watch the post window:</p>
50 <p class="p5"><span class="s3"><span class="Apple-tab-span"> </span></span><span class="s4">f = { </span>"Function evaluated"<span class="s4">.postln; };</span></p>
53 <p class="p3">Both times it should say '<span class="s5">a Function</span>'. Now whenever we want to refer to our Function we can just use the letter f. That's in fact what makes it reusable! Otherwise we'd need to type the Function in every time.</p>
55 <p class="p3">So how do we reuse it? Execute the following lines one at a time and watch the post window:</p>
57 <p class="p5"><span class="s4"><span class="Apple-tab-span"> </span>f = { </span>"Function evaluated"<span class="s4">.postln; };</span></p>
62 <p class="p3">Our Function is an object, (i.e a thing that does something or represents something), which we have defined and stored in the variable '<span class="s5">f</span>'. The bit of code that says '<span class="s5">.value</span>' says evaluate this function now. This is an example of sending a message to an object. This follows the syntax someObject.someMessage. The dot must go in between.</p>
64 <p class="p3">Now this next bit is a little bit tricky. In a given object, each <i>message</i> calls (calls means executes) a particular <i>method</i>. Different types of objects may have methods with the same name, and thus respond to the same message in different ways. Whoah, get that? Read it again slowly, as this is pretty important:</p>
66 <p class="p3"><i>Different types of objects may have methods with the same name, and thus respond to the same message in different ways.</i></p>
68 <p class="p3">What's interesting about this is that the actual methods may differ in what they do, but as long as they implement<span class="Apple-converted-space"> </span>a method with that name, they become interchangeable in your code.<span class="Apple-converted-space"> </span></p>
70 <p class="p3">A good example is 'value'. All objects in SC respond to the message 'value'. When you 'call' a method, it always 'returns' something, such as a value or a result. When you call the method 'value' on a Function it will evaluate and return the result of its last line of code. The example below will return the number 5.</p>
72 <p class="p4"><span class="s1"><span class="Apple-tab-span"> </span></span>f = { <span class="s6">"Evaluating..."</span>.postln; 2 + 3; };</p>
75 <p class="p3">Often methods simply return the object itself. This is the case with most objects and the message 'value'. The example below demonstrates this. (Everything to the right of the <span class="s7">//</span> is a 'comment', which means that SC just ignores it. Comments are a good idea to make your code clearer.)</p>
77 <p class="p7"><span class="s3"><span class="Apple-tab-span"> </span></span><span class="s4">f = 3;<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// Here I make f equal to a number</p>
78 <p class="p7"><span class="s4"><span class="Apple-tab-span"> </span>f.value;<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// Post window says: 3, i.e it returns itself</p>
79 <p class="p7"><span class="s4"><span class="Apple-tab-span"> </span>f.value;<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// Still says 3</p>
81 <p class="p7"><span class="s4"><span class="Apple-tab-span"> </span>f = { 3.0.rand; };<span class="Apple-tab-span"> </span></span>// Here it's a Function.<span class="Apple-converted-space"> </span></p>
82 <p class="p7"><span class="s4"><span class="Apple-tab-span"> </span>f.value;<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// 3.0.rand means return a random value from 0 to 3.0 exclusive.</p>
83 <p class="p7"><span class="s4"><span class="Apple-tab-span"> </span>f.value;<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// something different</p>
84 <p class="p7"><span class="s4"><span class="Apple-tab-span"> </span>f.value;<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// something different</p>
86 <p class="p3">This means that by using the 'value' method Functions and other objects can be interchangeable in your code. This is an example of <i>polymorphism</i>, which is one of the powerful features of what's called Object Oriented Programming. Polymorphism just means that different objects are interchangeable (at least providing they return something sensible for what you're doing) if they respond to the same message. Object Oriented Programming (or OOP, as it's called for short) just means programming with objects. Simple, yes? Here's another short example showing this in action:</p>
88 <p class="p7"><span class="s4"><span class="Apple-tab-span"> </span>f = { </span><span class="s2">arg</span><span class="s4"> a; a.value + 3 }; </span>// call 'value' on the arg; polymorphism awaits!</p>
89 <p class="p7"><span class="s4"><span class="Apple-tab-span"> </span>f.value(3);<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// 3.value = 3, so this returns 3 + 3 = 6</p>
91 <p class="p7"><span class="s4"><span class="Apple-tab-span"> </span>f.value(g);<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// here the arg is a Function. Cool, huh?</p>
92 <p class="p7"><span class="s4"><span class="Apple-tab-span"> </span>f.value(g);<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// try it again, different result</p>
96 <p class="p3">Functions can also have what are called arguments. These are values which are passed into the Function when it is evaluated. The example below demonstrates how this works. See if you can guess what the result will be before executing it.</p>
99 <p class="p4"><span class="Apple-tab-span"> </span>f = { <span class="s2">arg</span> a, b;<span class="Apple-converted-space"> </span></p>
100 <p class="p4"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>a - b;<span class="Apple-converted-space"> </span></p>
105 <p class="p3">Arguments are declared at the beginning of the Function, using the keyword '<span class="s8">arg</span>'. You can then refer to them just like variables. When you call value on a Function, you can pass in arguments, in order, by putting them in parentheses: <span class="s5">someFunc.value(arg1, arg2)</span>. This is the same with any method that takes arguments, not just value.</p>
109 <p class="p4"><span class="s1"><span class="Apple-tab-span"> </span></span>f = { <span class="s2">arg</span> a, b; a / b; }; <span class="Apple-tab-span"> </span><span class="s9">// '/' means divide</span></p>
110 <p class="p4"><span class="Apple-tab-span"> </span>f.value(10, 2); <span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s9">// regular style</span></p>
111 <p class="p4"><span class="Apple-tab-span"> </span>f.value(b: 2, a: 10); <span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s9">// keyword style</span></p>
113 <p class="p3">You can mix regular and keyword style if you like, but the regular args must come first:</p>
115 <p class="p4"><span class="s1"><span class="Apple-tab-span"> </span></span>f = { <span class="s2">arg</span> a, b, c, d; (a + b) * c - d };</p>
116 <p class="p4"><span class="Apple-tab-span"> </span>f.value(2, c:3, b:4, d: 1); <span class="s9">// 2 + 4 * 3 - 1</span></p>
118 <p class="p3">(Note that SC has no operator precedence, i.e. math operations are done in order, and division and multiplication are not done first. To force an order use parentheses. e.g. 4 + (2* 8) )</p>
120 <p class="p3">Sometimes it's useful to set default values for arguments. You can do this like so:</p>
122 <p class="p4"><span class="s1"><span class="Apple-tab-span"> </span></span>f = { <span class="s2">arg</span> a, b = 2; a + b; };</p>
123 <p class="p4"><span class="Apple-tab-span"> </span>f.value(2); <span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s9">// 2 + 2</span></p>
125 <p class="p3">Default values must be what are called literals. Literals are basically numbers, strings, symbols (more on these later), or collections of them. Don't worry if that doesn't totally make sense, it will become clearer as we go on.</p>
127 <p class="p3">There is an alternate way to specify args, which is to enclose them within two vertical lines. (On most keyboards the vertical line symbol is Shift-\ ) The following two Functions are equivalent:</p>
129 <p class="p4"><span class="s1"><span class="Apple-tab-span"> </span></span>f = { <span class="s2">arg</span> a, b; a + b; };</p>
130 <p class="p4"><span class="Apple-tab-span"> </span>g = { <span class="s2">|a, b|</span> a + b; };</p>
134 <p class="p3">Why have two different ways? Well some people like the second one better and consider it a shortcut. SC has a number of syntax shortcuts like this, which can make writing code a little faster. In any case you will encounter both forms, so you need to be aware of them.</p>
136 <p class="p3">You can also have variables in a Function. These you need to declare at the beginning of the Function, just after the args, using the keyword '<span class="s8">var</span>'.</p>
140 <p class="p4"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s2">var</span> firstResult, finalResult;</p>
141 <p class="p4"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>firstResult = a + b;</p>
142 <p class="p4"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>finalResult = firstResult * 2;</p>
143 <p class="p4"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>finalResult;</p>
145 <p class="p7"><span class="s4"><span class="Apple-tab-span"> </span>f.value(2, 3); <span class="Apple-tab-span"> </span></span>// this will return (2 + 3) * 2 = 10</p>
148 <p class="p3">Variable and argument names can consist of letters and numbers, but must begin with a lower-case letter and cannot contain spaces.</p>
150 <p class="p3">Variables are only valid for what is called their scope. The scope of a variable declared in a Function is that Function, i.e. the area between the two curly brackets. Execute these one at a time:</p>
152 <p class="p4"><span class="Apple-tab-span"> </span>f = { <span class="s2">var</span> foo; foo = 3; foo; };</p>
154 <p class="p7"><span class="s4"><span class="Apple-tab-span"> </span>foo;<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// this will cause an error as 'foo' is only valid within f.</p>
156 <p class="p3">You can also declare variables at the top of any block of code which you execute altogether (i.e. by selecting it all). In such a case that block of code is the variable's scope. Execute the block (in parentheses) and then the last line.</p>
160 <p class="p4"><span class="Apple-tab-span"> </span>myFunc = { <span class="s2">|input|</span> input.postln; };</p>
161 <p class="p4"><span class="Apple-tab-span"> </span>myFunc.value(<span class="s6">"foo"</span>); <span class="Apple-tab-span"> </span><span class="s9">// arg is a String</span></p>
162 <p class="p4"><span class="Apple-tab-span"> </span>myFunc.value(<span class="s6">"bar"</span>);</p>
165 <p class="p7"><span class="s4"><span class="Apple-tab-span"> </span>myFunc;<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// throws an error</p>
167 <p class="p3">You may be wondering why we haven't needed to declare variables like '<span class="s5">f</span>', and why they don't seem to have any particular scope (i.e. they keep there values even when executing code one line at a time). The letters a to z are what are called interpreter variables. These are pre-declared when you start up SC, and have an unlimited, or 'global', scope. This makes them useful for quick tests or examples. You've already encountered one of these, the variable '<span class="s5">s</span>', which you'll recall by default refers to the localhost server.</p>
171 <p class="p10"><a href="../../Language/Functions.html">Functions</a><span class="s4"><b> </b><a href="../../Core/Kernel/Function.html"><span class="s1">Function</span></a><b> </b><a href="../../Language/Assignment.html"><span class="s1">Assignment</span></a><b> </b><a href="../../Language/Intro-to-Objects.html"><span class="s1">Intro-to-Objects</span></a><b> </b><a href="../../Language/Literals.html"><span class="s1">Literals</span></a><b> </b><a href="../../Language/Scope.html"><span class="s1">Scope</span></a></span></p>
175 <p class="p3">This document is part of the tutorial <b>Getting Started With SuperCollider</b>.</p>
177 <p class="p3">Click here to go on to the next section: <a href="Functions and Sound.html"><span class="s10">Functions and Sound</span></a></p>
179 <p class="p3">Click here to return to the table of Contents: <a href="Getting Started With SC.html"><span class="s10">Getting Started With SC</span></a></p>
180 </body>
181 </html>